﻿@page "/docs/extensions/datagrid"
@page "/docs/extensions/datagrid/getting-started"

<Seo Canonical="/docs/extensions/datagrid/getting-started" Title="Blazorise DataGrid component" Description="Learn to use and work with the Blazorise DataGrid extension components to build an advanced CRUD based data-tables." />

<DocsPageTitle Path="Extensions/DataGrid">
    Blazorise DataGrid: Getting Started
</DocsPageTitle>

<DocsPageLead>
    The <Code>DataGrid</Code> component is used for displaying tabular data. Features include sorting, searching, pagination, content-editing, and row selection.
</DocsPageLead>

<DocsPageParagraph>
    <LicenseLimitationAlert LimitText="@($"{Licensing.BlazoriseLicenseProvider.DEFAULT_UNLICENSED_LIMIT_DATAGRID_MAX_ROWS} items")" />
</DocsPageParagraph>

<DocsPageParagraph>
    To create a basic grid in Blazorise you need to set the Column that will define the grid structure and behavior.
</DocsPageParagraph>

<UnorderedList>
    <UnorderedListItem>
        <Code Tag>DataGrid</Code> the main <Strong>container</Strong>
        <UnorderedList>
            <UnorderedListItem>
                <Code Tag>DataGridColumns</Code> container for datagrid columns
                <UnorderedList>
                    <UnorderedListItem><Code Tag>DataGridColumn</Code> column template for text editor</UnorderedListItem>
                    <UnorderedListItem><Code Tag>DataGridNumericColumn</Code> column template for numeric values</UnorderedListItem>
                    <UnorderedListItem><Code Tag>DataGridDateColumn</Code> column template for datetime values</UnorderedListItem>
                    <UnorderedListItem><Code Tag>DataGridCheckColumn</Code> column template for boolean values</UnorderedListItem>
                    <UnorderedListItem><Code Tag>DataGridSelectColumn</Code> column template for selectable values</UnorderedListItem>
                    <UnorderedListItem><Code Tag>DataGridCommandColumn</Code> column template for editing commands like Edit, Save, Cancel, etc.</UnorderedListItem>
                </UnorderedList>
            </UnorderedListItem>
            <UnorderedListItem>
                <Code Tag>DataGridAggregates</Code> container for datagrid aggregates
                <UnorderedList>
                    <UnorderedListItem><Code Tag>DataGridAggregate</Code> defines the column and aggregation function type</UnorderedListItem>
                </UnorderedList>
            </UnorderedListItem>
        </UnorderedList>
    </UnorderedListItem>
</UnorderedList>

<DocsPageSubtitle>
    Installation
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="NuGet">
        Install extension from NuGet.
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="DataGridNugetInstallExample"></DocsPageSectionSource>
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Imports">
        In your main <Badge Color="Color.Light">_Imports.razor</Badge> add:
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="DataGridImportsExample"></DocsPageSectionSource>
</DocsPageSection>

<DocsPageSubtitle>
    Usage
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="DataGrid">
        For DataGrid the required fields are <Code>TItem</Code> typeparam and Data attribute. Other attributes on the <Code>DataGrid</Code> are optional.
    </DocsPageSectionHeader>
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Columns">
        Next you must set the Columns that you want to see in the grid. When defining the columns the required fields are:
        <UnorderedList>
            <UnorderedListItem><Code>TItem</Code> this is always the same model as on <Code>DataGrid</Code>. And you should be able to omit this on recent versions of Blazorise</UnorderedListItem>
            <Code>Field</Code> name of the field in the supplied model.
            <Code>Caption</Code> the column caption text.
        </UnorderedList>
        <Alert Color="Color.Warning" Visible>
            <AlertDescription>
                Throughout our examples you may see the usage of <Blazorise.Link To="https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/nameof" Target="Target.Blank"><Code>nameof</Code></Blazorise.Link> when defining the <Code>Field</Code> Parameter.
                Note that <Code>nameof</Code> produces only the name of the variable, type or member as the string constant. It is used as a way to strongly type the string that represents our field.
                Please note, that this is not mandatory. And you may provide a regular string that represents the path to the field you want to be binding.
            </AlertDescription>
        </Alert>
    </DocsPageSectionHeader>
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Nested fields">
        Field attribute also supports nested fields. You can define a column with field name like <Code>"City.Country.Name"</Code> and it will work. Just keep in mind that when editing nested fields they must be initialized first or otherwise they will raise an exception.
    </DocsPageSectionHeader>
</DocsPageSection>

<Alert Color="Color.Info" Visible>
    <AlertDescription>
        <strong>Note:</strong> DataGrid supports the <Code>CascadingTypeParameter</Code> feature. We've found out, that there might be a few caveats when using the feature. For most cases you'll be just fine with removing the explicit references to the Generic Type on the children component. But for the very few cases that Blazor complains that it cannot compile, just explicitly define the Generic Type.
        Here's an example:
        <Paragraph Class="mb-0">
            This will not work:
        </Paragraph>
        <Paragraph>
            <Code>&lt;DataGridAggregate Field="@@nameof( Employee.IsActive )" AggregationFunction=@@(DataGridAggregate&lt;Employee&gt;.TrueCount) /&gt;</Code>
        </Paragraph>
        <Paragraph Class="mb-0">
            These will work:
        </Paragraph>
        <Paragraph Class="m-0">
            <Code>&lt;DataGridAggregate Field="@@nameof( Employee.IsActive )" AggregationFunction=@@((x,y) => DataGridAggregate&lt;Employee&gt;.TrueCount(x,y)) /&gt;</Code>
        </Paragraph>
        <Paragraph Class="m-0">
            <Code>&lt;DataGridAggregate TItem="Employee" Field="@@nameof( Employee.IsActive )" AggregationFunction=@@(DataGridAggregate&lt;Employee&gt;.TrueCount) /&gt;</Code>
        </Paragraph>
    </AlertDescription>
</Alert>

<DataGridApi></DataGridApi>